背景:为什么需要换主题
OpenClaw 的界面(Control UI、对话卡片、进度卡)有默认配色,但每个人屏幕环境、夜间使用习惯不同。有人要深色护眼,有人要浅色清爽,还有人想挂上自己写的一套配色。
很多人以为换皮肤要去改 nginx 或者动前端源码,其实 OpenClaw 已经内置了一个专门的 theme 工具,面向「当前请求用户」的外观做读写,不需要碰任何配置文件。
真实机制拆解
theme 工具暴露了几个动作,全部围绕「当前请求用户」的 OpenClaw 外观:
list:列出所有可用主题,包含内置主题(built-in)、插件提供的主题(plugin),以及个人主题(personal),每条都带描述和当前是否被选中的标记。
get:查看当前选中主题的详情,确认自己现在到底挂在哪套配色上。
- 切换动作:把请求用户的外观切到指定主题。注意它的作用范围是当前请求用户,不是全局 gateway,也不是别的用户——这点和很多「改一处全站生效」的直觉不同。
关键认知:theme 改的是「请求用户」这一层,不是全局。 你在自己的会话里切主题,只影响你看到的界面;其他用户/其他会话看到的是他们各自的外观设置。这也是为什么官方把它设计成「请求用户级」而不是「管理员全局级」——外观是私人体验,不该被一个人统一掉。
实战:列出并读懂主题清单
调用 theme 的 list 动作,返回结构大致是:
- 一组主题条目,每条有
id(内部标识)、name(展示名)、source(builtin / plugin / personal)、description、current(是否当前选中)。
- 通常还会单独标出
current selection,方便你一眼确认现状。
读这份清单时,重点看三列:
- source:builtin 永不过时、最稳;plugin 主题随插件启用而存在,卸载插件会消失;personal 是你自己上传/编写的,优先级最高也最私人。
- description:有的主题注明「适合 OLED 暗屏」「高对比度护眼」,按你的屏幕挑。
- current:为 true 的那条就是你现在的皮肤,切换前先确认它不是你已经用着的,避免「切了个寂寞」。
实战:切到目标主题
确定目标主题的 id 后,用切换动作把外观指过去。常见踩坑:
- 只传了 name 没传 id:清单里 name 可能重复或带空格,稳妥做法是传 list 返回的精确
id。
- 切换后没刷新:Control UI 有时需要重新加载视图才体现新配色,切完若看着没变,先刷新一次再下结论。
- 误以为全局生效:如前所述,这只改当前请求用户,别人看不到你的新皮肤,也别指望它改 gateway 默认的登录页配色。
实战踩坑提醒
- 个人主题是私有的:personal 主题只对创建它的用户可见、可切。你给同事发一个 personal 主题 id,他那边 list 里根本不会有这条。
- 插件主题随插件生死:依赖某个插件提供的主题时,禁用/卸载该插件,主题会直接从 list 里消失,界面会回退到内置默认——不是 bug,是预期行为。
- 不要为了「统一品牌形象」去全局改外观:OpenClaw 把外观设计成用户级,强行用其它手段全局覆盖,只会和原生机制打架,升级时最容易裂。
- 核验永远用 list 而不是记忆:可用主题会随插件/版本变化,写脚本或文档时,先
list再取 id,别硬编码一个可能已经不存在的主题名。
小结
theme 是 OpenClaw 里一个被低估的小工具:它把「换皮肤」这件事从改配置、碰前端的苦活,收敛成一次工具调用。list 看全貌、get 确认现状、再用 id 精准切换,既安全又不会误伤别人。记住它的作用域是当前请求用户,你就避开了 90% 的困惑。
把界面调成自己顺眼的样子,长期来看是在为每天几十次的开合会话省注意力——这本身就是一种低成本的生产力投资。
扫码关注公众号，获取更多 OpenClaw 实操技巧：
